<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
  <meta name="Description" content="">
  <meta name="Keywords"
 content="DAE Tools Project, pyDAE, cxxDAE, dynamic modelling, simulation, partial differential equations, dae, pdae, equation-oriented modelling">
  <meta http-equiv="Content-Type"
 content="text/html; charset=ISO-8859-1">
  <meta name="Distribution" content="Copyrighted">
  <meta name="Author" content="Dragan Nikolic - dnikolic@daetools.com">
  <meta name="Robots" content="index,follow">
  <link rel="stylesheet" href="images/dae.css" type="text/css">
  <title>DAE Tools project</title>
</head>
<body>
<!-- wrap starts here -->
<div id="wrap">
<div id="header">
<div id="header-content">
<h1 id="logo"><a href="index.html" title="">DAE Tools<span class="gray">
Project</span></a></h1>
<h2 id="slogan">Model the world freely...</h2>
<!-- Menu Tabs -->
<ul>
  <li><a href="index.html">Home</a></li>
  <li><a href="news.html">News</a></li>
  <li><a href="downloads.html">Downloads</a></li>
  <li><a href="documentation.html" id="current">Documentation</a></li>
  <li><a href="http://forum.daetools.com/">Forum</a></li>
  <li><a href="http://code.google.com/p/dae-tools">SVN</a></li>
  <li><a href="contact.html">About</a></li>
</ul>
</div>
</div>
<!-- content-wrap starts here -->
<div id="content-wrap">
<div id="content">
<div id="sidebar">
<div class="sidebox">
<h1 class="clear">Getting Started</h1>
<ul class="sidemenu">
  <li><a href="#Programming_language">Programming language</a></li>
  <li><a href="#The_main_concepts">The main concepts</a></li>
  <li><a href="#Running_a_simulation">Running a simulation</a></li>
  <li><a href="#1._Model_Development" class="top">Modelling<br>
    </a></li>
  <li>
    <p><a href="#Models" id="current">Models</a></p>
    <p><a href="#Distribution_domains">Distribution Domains</a></p>
    <p><a href="#Parameters">Parameters</a></p>
    <p><a href="#Variables">Variables</a></p>
    <p><a href="#Equations">Equations</a></p>
    <p><a href="#State_transition_networks">STNs</a></p>
    <p><a href="#Ports">Ports</a></p>
  </li>
  <li><a href="#2._Definition_of_a_simulation">Simulation</a></li>
  <li><a href="#3._Processing_of_the_results">Processing the
results</a></li>
</ul>
</div>
</div>
<div id="main">
<div class="post"><!-- Getting Started   -->
<h1><a name="Getting_Started"></a>Getting Started</h1>
<p>This chapter gives the basic
information about what is needed to develop a model of a
process, how to simulate it and&nbsp; how to obtain and plot
the results of a process simulation. In general,&nbsp;<span
 style="font-weight: bold;"></span>the simulation of a process consists
of three tasks:</p>
<ol>
  <li>Modelling of a proces<br>
  </li>
  <li>Defining a simulation</li>
  <li>Processing the results</li>
</ol>
<h2><a name="Programming_language"></a>Programming language</h2>
<p><span style="font-weight: bold;">DAE Tools</span> core libraries are
written in standard c++. However, <a href="http://www.python.org/">Python</a>
programming language is used
as the main modelling language. The main reason for use of Python is
(as the authors say):&nbsp; <span style="font-style: italic;">"Python
is an easy to learn, powerful programming language. It has efficient
high-level data structures and a simple but effective approach to
object-oriented programming. Python&#8217;s elegant syntax and dynamic
typing, together with its interpreted nature, make it an ideal language
for scripting and rapid application development in many areas on most
platforms" <a href="http://docs.python.org/tutorial/"><sup>[*]</sup></a></span>.<span
 style="font-style: italic;"> </span>And: "<span
 style="font-style: italic;">Often, programmers fall in love with
Python because of the increased productivity it provides. Since there
is no compilation step, the edit-test-debug cycle is incredibly fast" </span><span
 style="font-style: italic;"><a
 href="http://www.python.org/doc/essays/blurb/"><sup>[*]</sup></a></span><span
 style="font-style: italic;"></span>. Also, please have a look on <a
 href="http://www.python.org/doc/essays/comparisons/">a comparison to
the other languages</a>. Based on the information available online, and
according to the personal experience, the python programs are much
shorter and take an order of magnitude less time to develop it.
Initially I developed daePlotter module in c++; it took me about one
month of part time coding. But, then I moved to python:&nbsp;
reimplementing it in PyQt took me just two days (with several new
features added), while
the code size shrank from 24 cpp modules to four python modules only! <span
 style="font-style: italic;">"Where Python code is typically 3-5 times
shorter than equivalent Java code, it is often 5-10 times shorter than
equivalent C++ code! Anecdotal evidence suggests that one Python
programmer can finish in two months what two C++ programmers can't
complete in a year. Python shines as a glue language, used to combine
components written in C++"</span><span style="font-style: italic;"> </span><span
 style="font-style: italic;"><a
 href="http://www.python.org/doc/essays/comparisons/"><sup>[*]</sup></a></span><span
 style="font-style: italic;"></span>. Obviously, not everything can be
developed in python; for complex projects I still prefer the heavy c++
artillery.</p>
<h2><a name="The_main_concepts"></a>The main concepts<br>
</h2>
<p>To efficiently model a real world user should be familiar with the
following concepts<span style="font-weight: bold;"></span>:</p>
<ul>
  <li><span style="font-weight: bold;">Model<br>
    </span>A model of the
process is a simplified abstraction of real world process/phenomena
describing its most important/driving elements and their interactions.
In <span style="font-weight: bold;">DAE Tools</span> models are
created by defining their parameters,
distribution domains, variables, equations, and ports. </li>
  <ul>
    <li><span style="font-weight: bold;">Distribution domain</span><br>
Domain is a general term used
to define an array of different objects (parameters, variables,
equations but models and ports as well).<br>
    </li>
    <li><span style="font-weight: bold;">Parameter</span> <br>
Parameter can be defined as a time invariant quantity that will not
change during
a simulation.<br>
    </li>
    <li><span style="font-weight: bold;">Variable</span> <br>
Variable can be defined as a time variant quantity, also called a <span
 style="font-style: italic;">state variable</span>.<br>
    </li>
    <li style="font-weight: bold;">Equation<br>
      <span style="font-weight: normal;">Equation can be defined as an
expression used to calculate a variable value, which can be created by
performing basic mathematical operations (+, -, *, /) and functions
(such as sin, cos, tan, sqrt, log, ln, exp, pow, abs etc) on
parameter and variable values (and time and partial derivatives as well)</span>.<br>
    </li>
    <li><span style="font-weight: bold;">State transition network</span>
      <br>
State transition networks are used to model a special type of
equations: <span style="font-style: italic;">discontinuous equation</span>s.
Discontinuous
equations
are
equations
that
take
different
forms
subject
to
certain
conditions.
They
are composed of a finite number of <span style="font-style: italic;">states.</span><br>
    </li>
    <li style="font-weight: bold;">State<br>
      <span style="font-weight: normal;">States can be defined as a set
of actions (in our case a set of equations) </span><span
 style="font-weight: normal;">under current operating conditions. In
addition, every
state contains </span><span style="font-weight: normal;">a set of
state transitions which describe conditions when the state changes
occur.</span><br>
    </li>
    <li><span style="font-weight: bold;">State Transition</span><br>
State transition can be defined as a transition from the current to
some other state, subject to given conditions. <br>
    </li>
    <li><span style="font-weight: bold;">Port</span><br>
Ports are objects used to connect two models. Like models, they may
contain
domains, parameters and variables. <br>
    </li>
  </ul>
  <li style="font-weight: bold;">Simulation<br>
    <span style="font-weight: normal;">Simulation of a process can be
considered as the model run for certain input conditions.</span> <span
 style="font-weight: normal;">To define a simulation, several tasks are
necessary such as: specifying information about domains and parameters,
fixing the degrees of freedom by assigning values to certain variables,
setting the initial conditions and many other (setting the initial
guesses,
absolute tolerances, etc).</span></li>
  <li><span style="font-weight: bold;">Solver</span><br>
Solver is a set of mathematical procedures/algorithms necessary to
solve a given set of equations. There are several types of solvers:
Linear algebraic solvers (<span style="font-weight: bold;">LA</span>),
used to solve linear systems of equations; Nonlinear
Algebraic solvers (<span style="font-weight: bold;">NLA</span>), used
to solve non-linear systems of equations;&nbsp; Differential
Algebraic solvers (<span style="font-weight: bold;">DAE</span>), used
to solve mixed systems of differential and algebraic
equations. In <span style="font-weight: bold;">DAE Tools</span> it is
possible to choose <span style="font-weight: bold;">DAE</span>
(curently only <a
 href="https://computation.llnl.gov/casc/sundials/main.html">Sundials
IDA</a>) and <span style="font-weight: bold;">LA</span> solvers
(currently built-in Sundials LA solvers, <a
 href="http://software.intel.com/en-us/intel-mkl/">Intel MKL</a>, <a
 href="http://www.amd.com/acml">AMD ACML</a>, <a
 href="http://trilinos.sandia.gov/packages/amesos/">Trilinos Amesos</a>,
and
Lapack).
&nbsp;
  </li>
  <li style="font-weight: bold;">Data Reporter<br>
    <span style="font-weight: normal;">Data reporter is defined as
an object used to report the results of the simulation. They can either
keep the results internally (and export them into a file, for instance)
or send them
via TCP/IP protocol to the <span style="font-weight: bold;">DAE Tools</span>
plotter.</span><br>
  </li>
  <li style="font-weight: bold;">Data Receiver<br>
    <span style="font-weight: normal;">Data receiver can be defined as
on object which duty is to receive the results from a data reporter.
These data can be later plotted or processed in some other ways.</span><br>
  </li>
  <li><span style="font-weight: bold;">Log</span><br>
Log is defined as an object used to send messages from the various
parts
of <span style="font-weight: bold;">DAE Tools</span> framework
(messages from a solver or simulation).<br>
  </li>
</ul>
<h2><a name="Running_a_simulation"></a>Running a simulation<br>
</h2>
<p>Two steps are needed to run a simulation:<br>
</p>
<ul>
  <li>Start <span style="font-weight: bold;">daePlotter</span>:</li>
</ul>
<pre><span style="font-weight: bold;">In GNU/Linux:</span><br>go to: <span
 style="font-weight: bold;">Applications/Programming/daePlotter</span><br>or type the following shell command: <span
 style="font-weight: bold;">daeplotter</span><br><br><span
 style="font-weight: bold;">In Windows:</span><br>go to: <span
 style="font-weight: bold;">Start/Programs/DAE Tools/daePlotter</span><br></pre>
<div style="text-align: left;">
<p>&nbsp;The <span style="font-weight: bold;">daePlotte</span>r main
window
should appear (given in <span style="font-weight: bold;">Figure 1.</span>)
<br>
</p>
</div>
<p style="text-align: center;"><br>
<img style="width: 406px; height: 240px;" alt=""
 src="images/Screenshot-DAEPlotter.png"><br>
</p>
<div style="text-align: center;"><span style="font-weight: bold;">Figure
1.
daePlotter
main
window<br>
<br>
</span><span style="font-weight: bold;"></span>
<p style="text-align: left;"><span style="font-weight: bold;">daePlotter</span>
can be also added to a panel. Simply add a custom application launcher
(command:
daeplotter)</p>
<span style="font-weight: bold;"></span><span style="font-weight: bold;"></span>
<p style="text-align: left;"><br>
</p>
<div style="text-align: left;">
<p><span style="font-weight: bold;"></span></p>
<p><span style="font-weight: bold;"></span></p>
</div>
</div>
<ul>
  <li>Start <span style="font-weight: bold;">DAE Tools Examples</span>
program to try some examples:</li>
</ul>
<pre><span style="font-weight: bold;">In GNU/Linux:<br></span>go to: <span
 style="font-weight: bold;">Applications/Programming/DAE Tools Examples<br></span>or type the following shell command: <span
 style="font-weight: bold;">daeexamples</span><br><br><span
 style="font-weight: bold;"></span><span style="font-weight: bold;">In Windows:</span><br>go to: <span
 style="font-weight: bold;">Start/Programs/DAE Tools/</span><span
 style="font-weight: bold;">DAE Tools Examples<br><br></span></pre>
<p>In general, simulations are started by typing the following shell
commands (GNU/Linux and Windows):</p>
<pre>$ cd "directory where simulation file is located"<br>$ python mySimulation.py<br></pre>
<p>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; The main window of <span
 style="font-weight: bold;">DAE Tools Examples</span> application is
given in <span style="font-weight: bold;">Figure 2a.</span> while the
output from the simulation run in<span style="font-weight: bold;"> </span><span
 style="font-weight: bold;">Figure 2b. </span>Users can select one of
several tutorials, run them, and inspect their source
code or model reports. Model reports open in a new window of the
system's default web browser (however, only Mozilla Firefox is
currently
supported because of the MathML rendering issue).<br>
<span style="font-weight: bold;"><br>
</span></p>
<p style="text-align: center;"><span style="font-weight: bold;"><img
 style="width: 515px; height: 199px;" alt=""
 src="images/Screenshot-DAEToolsTutorials.png"><br>
</span></p>
<div style="text-align: center;"><span style="font-weight: bold;">Figure
2a.
DAE
Tools
Examples
main window<br>
<br>
</span><span style="font-weight: bold;"><img
 style="width: 570px; height: 582px;" alt=""
 src="images/Screenshot-DAEToolsTutorials-Run.png"></span><br>
<span style="font-weight: bold;"></span></div>
<div style="text-align: center;"><span style="font-weight: bold;">Figure
2b.
Simulation&nbsp;
output
from
DAE
Tools
Examples
program</span><br>
<span style="font-weight: bold;"></span></div>
<p></p>
<p></p>
<p><br>
</p>
<p>The simulation can also be started from the shell. The sample output
is given in<span style="font-weight: bold;"> </span><span
 style="font-weight: bold;">Figure
3.<br>
<br>
</span></p>
<div style="text-align: center;"><img
 style="width: 404px; height: 600px;" alt=""
 src="images/Screenshot-RunningSimulation.png"><br>
</div>
<p></p>
<div style="text-align: center;"><span style="font-weight: bold;">Figure
3.
Shell
output
from
the
simulation<br>
</span><span style="font-weight: bold;"></span>
</div>
<p><br>
<br>
</p>
<h2><a name="1._Model_Development"></a>Modelling</h2>
<p>In general, three approaches to process modelling exist <a
 href="#1_Morton_W._Equation-oriented"><sup>[1]</sup></a>:<br>
</p>
<ul>
  <li>Sequential Modular (<span style="font-weight: bold;">SeqM</span>)
approach<br>
  </li>
  <li>Simultaneous Modular (<span style="font-weight: bold;">SimM</span>)
approach</li>
  <li>Equation-Oriented (<span style="font-weight: bold;">EO</span>)
approach</li>
</ul>
<p> &nbsp; The pros &amp; cons of the first two approaches are
extensively studied in the literature. Under the <span
 style="font-weight: bold;">EO</span> approach we generate and gather
together all equations and variables which constitute the model
representing the process. The equations are solved simultaneously using
a suitable mathematical algorithm <a
 href="getting_started.html#1_Morton_W._Equation-oriented"><sup>[1]</sup></a>.
Equation-oriented
simulation
requires
simultaneous
solution
of
a
set
of
differential
algebraic
equations
(<span style="font-weight: bold;">DAE</span>)
which
itself
requires
a
solution
of
a
set
of nonlinear algebraic
equations (<span style="font-weight: bold;">NLAE</span>) and linear
algebraic equations (<span style="font-weight: bold;">LAE</span>). The
Newton's method or some variant of it is almost always used to solve
problems described by NLAEs. A brief history of Equation-Oriented
solvers and comparison of <span style="font-weight: bold;">SeqM</span>
and <span style="font-weight: bold;">EO</span> approaches as well as
descriptions of the simultaneous modular and equation-oriented methods
can be found in <a
 href="getting_started.html#1_Morton_W._Equation-oriented"><sup>[1]</sup></a>.
Also
a
good
overview
of
the
equation-oriented
approach
and
its
application
in
<a href="http://www.psenterprise.com/gproms/">gPROMS</a>
is given by Barton &amp; Pantelides <sup><a
 href="#Pantelides_C._C._and_P._I._Barton1">[2]</a>, <a
 href="#Barton_P._I._and_C._C._Pantelides2">[3]</a>, <a
 href="#Barton_P._I._and_C._C._Pantelides3">[4]</a></sup>. <br>
</p>
<p><span style="font-weight: bold;">DAE Tools</span> use
the Equation-Oriented approach to process
modelling, and the following
types of processes can be modelled: <br>
</p>
<ul>
  <li>Lumped and distributed</li>
  <li>Steady-state and dynamic<br>
  </li>
</ul>
<p>Problems can be
formulated as linear, non-linear, and (partial) differential algebraic
systems (of index 1). The most common problems are initial value
problems of implicit form. Equations can be ordinary or
discontinuous, where discontinuities are automatically handled by the
framework. A good overview of discontinuous equations and a procedure
for location of equation discontinuities is given by Park &amp; Barton <a
 href="#Park_T._and_P._I._Barton"><sup>[5]</sup></a> and in Sundials
IDA <a
 href="https://computation.llnl.gov/casc/sundials/documentation/ida_guide/node3.html#SECTION00330000000000000000">documentation</a>
(used in DAE Tools).&nbsp; </p>
<p><br>
</p>
<p><sup><a name="1_Morton_W._Equation-oriented"></a></sup><small><span
 style="font-weight: bold;">[1]</span> Morton, W., Equation-Oriented
Simulation and Optimization. <span style="font-style: italic;">Proc.
Indian Natl. Sci. Acad.</span> 2003,
317&#8211;357.<br>
</small></p>
<div class="biblio-entry"><small>
</small>
<div class="biblio-style-ieee">
<p><small><span class="biblio-authors"><a
 name="Pantelides_C._C._and_P._I._Barton1"></a></span><span
 class="biblio-authors"><span style="font-weight: bold;">[2] </span></span><span
 class="biblio-authors">Pantelides, C. C., and P. I. Barton, </span><span
 class="biblio-title">"<a
 href="http://www.sciencedirect.com/science/article/B6TFT-44W51XS-1F/2/bf701c7635c1f5bfdff558b9ef69a3c2">Equation-oriented
dynamic
simulation
current
status
and
future
perspectives</a>", </span><i>Computers
&amp;
Chemical Engineering</i>, vol. 17, no. Supplement 1, pp. 263 -
285, 1993.<span class="biblio-abstract-link"><a
 href="http://yoric.mit.edu/node/247"><br>
</a></span></small></p>
<small><span class="biblio-abstract-link"></span>
</small></div>
</div>
<p><small><span class="biblio-authors"><a
 name="Barton_P._I._and_C._C._Pantelides2"></a></span><span
 class="biblio-authors"><span style="font-weight: bold;">[3]</span> </span><span
 class="biblio-authors">Barton, P. I., and C. C. Pantelides, </span><span
 class="biblio-title">"<a href="http://yoric.mit.edu/biblio/view/246">gPROMS
-
a
Combined
Discrete/Continuous
Modelling
Environment
for
Chemical
Processing
Systems</a>", </span><i>Simulation Series</i>, vol. 25, no.
3, pp. 25-34, 1993.
</small></p>
<p><small><span class="biblio-authors"><a
 name="Barton_P._I._and_C._C._Pantelides3"></a><span
 style="font-weight: bold;">[4]</span> Barton, P. I., and C. C.
Pantelides, </span> <span class="biblio-title">"<a
 href="http://dx.doi.org/10.1002/aic.690400608">Modeling of combined
discrete/continuous processes</a>", </span> <i>AIChE Journal</i>,
vol. 40, pp. 966-979, 1994.<br>
</small></p>
<p><small><span class="biblio-authors"><a
 name="Park_T._and_P._I._Barton"></a><span style="font-weight: bold;">[5]</span>
Park, T., and P. I. Barton, </span><span class="biblio-title">"<a
 href="http://yoric.mit.edu/biblio/view/241">State event location in
differential-algebraic models</a>", </span><i>ACM Transactions on
Modeling and Computer Simulation</i>, vol. 6, no. 2, New York, NY, USA,
ACM, pp. 137&#8211;165, 1996.</small>
<br>
</p>
<h3><a name="Models"></a>Models</h3>
<p>In <span style="font-weight: bold;">DAE Tools</span> models
are created by defining its parameters,
distribution domains, variables, equations, and ports.
Models are developed by deriving a new class from the base model class
(<span style="font-weight: bold;">daeModel</span>). The process
consists of two steps:<br>
</p>
<ol>
  <li>Declare all domains, parameters, variables and ports in <span
 style="font-style: italic;">__init__</span> function (the
constructor)</li>
  <li>Declare equations and state transition networks in <span
 style="font-style: italic;">DeclareEquations </span>function<br>
  </li>
</ol>
<p>Models in <span style="font-weight: bold;">pyDAE</span> (using
python programming language) can be
defined by the following statement:<br>
</p>
<pre>class myModel(daeModel):<br>    def __init__(self, Name, Parent = None, Description = ""):<br>        daeModel.__init__(self, Name, Parent, Description)<br>        ... (here go declarations of domains, parameters, variables, ports, etc)<br><br>    def DeclareEquations(self):<br>        ... (here go declarations of equations and state transitions)<br></pre>
<p>while in <span style="font-weight: bold;">cDAE</span> (using c++
programming language):<br>
</p>
<pre>class myModel : public daeModel<br>{<br>public:<br> &nbsp;&nbsp; myModel(string strName, daeModel* pParent = NULL, string strDescription = "") <br>       : daeModel(strName, pParent, strDescription)<br>    {<br>        ... (here go additional properties of domains, parameters, variables, ports, etc)<br>    }<br><br>&nbsp;&nbsp;&nbsp; void DeclareEquations(void)<br>&nbsp;&nbsp;&nbsp; {<br>        ... (here go declarations of equations and state transitions)<br>   &nbsp;}<br><br>public:<br>    ... (here go declarations of domains, parameters, variables, ports, etc)<br>};</pre>
<p>More information about developing models can be found in <a
 href="user_guide.html">pyDAE User Guide</a> and <a
 href="api_ref/core.html#daeModel">pyDAE API Reference</a>. Also, do
not forget to have a look on <a href="tutorials.html">tutorials</a>.</p>
<h3><a name="Distribution_domains"></a>Distribution domains</h3>
<p>There are two types of domains in <span style="font-weight: bold;">DAE
Tools</span>: simple arrays and distributed domains (commonly&nbsp;
used to distribute variables, parameters and equations in space). The
distributed domains can have a uniform (default) or a user specified
non-uniform grid. At the moment, only the following finite difference
methods can be
used to calculate partial derivatives:<br>
</p>
<ul>
  <li>Backward finite difference method (BFD)<br>
  </li>
  <li>Forward finite difference method (FFD)<br>
  </li>
  <li>Center finite difference method (CFD)<br>
  </li>
</ul>
<p>In <span style="font-weight: bold;">DAE Tools</span> just anything
can be distributed on domains:
parameters, variables, equations even models and ports. Obviously it
does not have a physical meaning to distribute a model on a domain,
However that can be&nbsp; useful for modelling of complex processes
where
we can create an array of models where each point in a distributed
domain have a corresponding model so that a user does not have to take
care of number of points in the domain, etc. In addition, domain points
values
<span style="font-style: italic;"></span>can be obtained as a <span
 style="font-weight: bold;">NumPy</span>
one-dimensional array; this way <span style="font-weight: bold;">DAE
Tools</span> can be easily used in conjuction with other scientific
python libraries (<a href="http://numpy.scipy.org/">NumPy</a>, <a
 href="http://www.scipy.org">SciPy</a>, for instance and many <a
 href="http://www.scipy.org/Projects">other</a>)<span
 style="font-style: italic;">.<br>
</span></p>
<p>Domains in <span style="font-weight: bold;">pyDAE</span> can be
defined by the following statement:</p>
<pre>myDomain = daeDomain("myDomain", Parent_Model_or_Port, Description)</pre>
<p>while in <span style="font-weight: bold;">cDAE</span>:<br>
</p>
<pre>daeDomain myDomain("myDomain", &amp;Parent_Model_or_Port, Description);</pre>
<p>More information about domains can be found in <a
 href="user_guide.html">pyDAE User Guide</a> and <a
 href="api_ref/core.html#daeDomain">pyDAE API Reference</a>. Also, do
not forget to have a look on <a href="tutorials.html">tutorials</a>.</p>
<h3><a name="Parameters"></a>Parameters</h3>
<p>There are two types of parameters in <span
 style="font-weight: bold;">DAE Tools</span>: ordinary and distributed.
Several functions to get a parameter value (the function
call
operator)&nbsp;<span style="font-style: italic;"></span><span
 style="font-style: italic;"></span><span style="font-style: italic;"></span>and
array
of
values
(the
function
<span style="font-style: italic;">array</span><span
 style="font-style: italic;"></span><span style="font-style: italic;"></span>)
have
been
defined.
In
addition,
distributed
parameters
have
<span style="font-style: italic;">GetNumPyArray</span>
function to get the
values as a numpy multi-dimensional array<span
 style="font-style: italic;">.</span><br>
</p>
<p>Parameters in <span style="font-weight: bold;">pyDAE</span> can be
defined by the following statement:</p>
<pre>myParam = daeParameter("myParam", eReal, Parent_Model_or_Port, "Description")</pre>
<p>while in <span style="font-weight: bold;">cDAE</span>:<br>
</p>
<pre>daeParameter myParam("myParam", eReal, &amp;Parent_Model_or_Port, "Description");</pre>
<p>More information about parameters can be found in <a
 href="user_guide.html">pyDAE User Guide</a> and <a
 href="api_ref/core.html#daeParameter">pyDAE API Reference</a>. Also,
do not forget to have a look on <a href="tutorials.html">tutorials</a>.</p>
<h3><a name="Variables"></a>Variables</h3>
<p>There are two types of variables in <span style="font-weight: bold;">DAE
Tools</span>: ordinary and distributed. Functions to get a
variable value (function call operator), a time or a partial
derivative (<span style="font-style: italic;">dt</span>, <span
 style="font-style: italic;">d</span>, or <span
 style="font-style: italic;">d2</span>) or functions to obtain an array
of values, time or partial derivatives (<span
 style="font-style: italic;">array,
dt_array</span>, <span style="font-style: italic;">d_array</span>, or <span
 style="font-style: italic;">d2_array</span>) have been defined. In
addition, distributed variables have <span style="font-style: italic;">GetNumPyArray</span>
function to get the values as a numpy multi-dimensional array<span
 style="font-style: italic;">.<br>
</span></p>
<p>Variables in <span style="font-weight: bold;">pyDAE</span> can be
defined by the following statement:</p>
<pre>myVar = daeVariable("myVar", variableType, Parent_Model_or_Port, "Description")</pre>
<p>while in <span style="font-weight: bold;">cDAE</span>:<br>
</p>
<pre>daeVariable myVar("myVar", variableType, &amp;Parent_Model_or_Port, "Description");</pre>
<p>More information about variables can be found in <a
 href="pydae_user_guide.html">pyDAE User Guide</a> and <a
 href="api_ref/core.html#daeVariable">pyDAE API Reference</a>. Also, do
not forget to have a look on <a href="tutorials.html">tutorials</a>.<br>
</p>
<h3><a name="Equations"></a>Equations</h3>
<p><span style="font-weight: bold;">DAE Tools</span> introduce two
types of equations: ordinary and distributed.
What makes distributed equations special is that an equation expression
is valid on every point within the domains that the equations is
distriibuted on. Equations can be distributed on a whole domain, on a
part of it or on some of the points in a domain.<br>
</p>
<p>Equations in <span style="font-weight: bold;">pyDAE</span> can be
defined by the following statement:</p>
<pre>eq = model.CreateEquation("myEquation", "Description")</pre>
<p>while in <span style="font-weight: bold;">cDAE</span>:<br>
</p>
<pre>daeEquation* eq = model.CreateEquation("myEquation", "Description");</pre>
<p>
</p>
<p>To define an equation expression (used to calculate its residual and
its gradiant - which represent a single row in a Jacobian matrix) <span
 style="font-weight: bold;">DAE Tools </span>combine
the
<a
 href="http://en.wikipedia.org/wiki/Automatic_differentiation#Operator_overloading">operator
overloading</a> technique for <a
 href="http://en.wikipedia.org/wiki/Automatic_differentiation">automatic
differentiation</a> (adopted from <a
 href="https://projects.coin-or.org/ADOL-C"><span
 style="font-weight: bold;">ADOL-C</span></a> library) with the concept
of representing equations as <span style="font-weight: bold;">evaluation
trees</span>. Evaluation trees are made of binary or unary nodes,
itself representing four basic mathematical operations and frequently
used mathematical functions, such as sin, cos, tan, sqrt, pow, log, ln,
exp, min, max,&nbsp; floor, ceil, abs, sum, product, ...). These basic
mathematical operations and functions are implemented to operate on <span
 style="font-weight: bold;">a heavily modified ADOL-C</span> library
class <span style="font-weight: bold;">adouble </span>(which has been
extended to contain information about domains/parameters/variables
etc). In
adition, a new <span style="font-weight: bold;">adouble_array </span>class
has
been
introduced
to
apply
all
above-mentioned
operations
on
arrays
of
variables.&nbsp;
What
is
different
here
is
that
<span style="font-weight: bold;">adouble</span>/<span
 style="font-weight: bold;">adouble_array</span>
classes
and
mathematical
operators/functions work in two modes; they can either <span
 style="font-weight: bold;"></span> <span style="font-weight: bold;">build-up
an
evaluation
tree
</span>or <span style="font-weight: bold;">calculate a value of
an expression</span>.
Once built the evaluation trees can be used to calculate equation
residuals or
derivatives to fill a Jacobian matrix necessary for a Newtown-type
iteration. A typical evaluation tree is presented in <span
 style="font-weight: bold;">Figure 4.</span> below.<br>
</p>
<p><br>
</p>
<div style="text-align: center;"><img
 style="width: 378px; height: 416px;" alt="Evaluation tree"
 title="Evaluation tree" src="images/EvaluationTree.png"><br>
<span style="font-weight: bold;"><a
 name="Figure_1._DAE_Tools_equation_evaluation"></a>Figure 4. DAE Tools
equation evaluation tree</span><br>
<div style="text-align: left;">
<p><br>
</p>
<div style="text-align: justify;">
<p>As it has been noted before, domains, parameters, and variables
contain
functions that return <span style="font-weight: bold;">adouble</span>/<span
 style="font-weight: bold;">adouble_array</span> objects, which can be
used
to calculate residuals and derivatives. These functions include
functions to get a
value of a domain/parameter/variable (function call operator), to get a
time or a partial
derivative of a variable (functions <span style="font-style: italic;">dt</span>,
<span style="font-style: italic;">d</span>, or <span
 style="font-style: italic;">d2</span>) or functions to obtain an array
of values, time or partial derivatives (<span
 style="font-style: italic;">array,
dt_array</span>, <span style="font-style: italic;">d_array</span>, or <span
 style="font-style: italic;">d2_array</span>). Another useful feature
of <span style="font-weight: bold;">DAE Tools</span>
equations is that they can be exported into
MathML or Latex format and easily visualized.</p>
</div>
<p>For example, the equation <span style="font-style: italic;">F</span>
(given in <span style="font-weight: bold;">Figure 4.</span>) can be
defined in <span style="font-weight: bold;">pyDAE </span>by using the
following
statements:<br>
</p>
<pre>F = model.CreateEquation("F", "F description")<br>F.Residal = V14.dt() + V1() / (V14() + 2.5) + sin(3.14 * V3())<br></pre>
<p>while in <span style="font-weight: bold;">cDAE</span> by:<br>
</p>
<pre>daeEquation* F = model.CreateEquation("F", "F description");<br>F-&gt;SetResidal( V14.dt() + V1() / (V14() + 2.5) + sin(3.14 * V3()) );</pre>
</div>
</div>
<p>More information about equations can be found in <a
 href="pydae_user_guide.html">pyDAE User Guide</a> and <a
 href="api_ref/core.html#daeEquation">pyDAE API Reference</a>. Also, do
not forget to have a look on <a href="tutorials.html">tutorials</a>.<br>
</p>
<h3><a name="State_transition_networks"></a>State Transition Networks
(Discontinuous equations)</h3>
<p>Discontinuous equations are equations that take different forms
subject to certain conditions. For example, if we want to model a flow
through a pipe we may observe three different flow regimes:<br>
</p>
<ul>
  <li>Laminar: if Reynolds number is less than 2,100</li>
  <li>Transient: if Reynolds number is greater than 2,100 and less than
10,000</li>
  <li>Turbulent: if Reynolds number is greater than 10,000<br>
  </li>
</ul>
<p>What we can see is that from any of these three states we can go to
any other state. This type of discontinuities is called a <span
 style="font-weight: bold;">reversible discontinuity</span> and can be
described by the <span style="font-weight: bold;">IF - ELSE_IF - ELSE
state transient network
construct</span>. In <span style="font-weight: bold;">pyDAE</span>&nbsp;<span
 style="font-weight: bold;"></span>it is given by the following
statement:<br>
</p>
<pre>IF(Re() &lt;= 2100)                      # (Laminar flow)<br> ... (equations go here)<br><br>ELSE_IF(Re() &gt; 2100 and Re() &lt; 10000) # (Transient flow)<br> ... (equations go here)<br><br>ELSE()                                # (Turbulent flow)<br> ... (equations go here)<br><br>END_IF()<br></pre>
<p>while in <span style="font-weight: bold;">cDAE</span> by:</p>
<pre>IF(Re() &lt;= 2100);                      // (Laminar flow)<br> ... (equations go here)<br><br>ELSE_IF(Re() &gt; 2100 and Re() &lt; 10000); // (Transient flow)<br> ... (equations go here)<br><br>ELSE();                                // (Turbulent flow)<br> ... (equations go here)<br><br>END_IF();</pre>
<p><span style="font-weight: bold;">Reversible discontinuities</span>
can be <span style="font-weight: bold;">symmetrical</span>
and <span style="font-weight: bold;">non-symmetrical</span>. The above
example is <span style="font-weight: bold;">symmetrical</span>.
However, if we have a CPU and we want to model its power dissipation
we may have three operating modes with the following state transitions:<br>
</p>
<ul>
  <li>Normal mode<br>
&nbsp;&nbsp; - switch to <span style="font-style: italic;">Power
saving mode</span> if <span style="font-style: italic;">CPU load</span>
is below 5%<br>
&nbsp;&nbsp; - switch to <span style="font-style: italic;">Fried mode</span>
if the temperature is <span style="font-style: italic;"></span>above
110<sup>0</sup>C<br>
  </li>
  <li>Power saving mode<br>
&nbsp;&nbsp; - switch to <span style="font-style: italic;">Normal mode</span>
if <span style="font-style: italic;">CPU load</span> is above 5%<br>
&nbsp;&nbsp; - switch to <span style="font-style: italic;">Fried mode</span>
if the temperature is <span style="font-style: italic;"></span>above
110<sup>0</sup>C<br>
  </li>
  <li>Fried mode (no escape from here... go to the nearest shop and buy
a new one!)<br>
  </li>
</ul>
<p>What we can see is that from the <span style="font-style: italic;">Normal
mode</span> we can either go to the <span style="font-style: italic;">Power
saving
mode</span> or to the <span style="font-style: italic;">Fried
mode</span>. The same stands for the <span style="font-style: italic;">Power
saving
mode</span>: we can either go to the <span style="font-style: italic;">Normal
mode</span> or to the <span style="font-style: italic;">Fried mode.</span>
However, once the
temperature exceeds 110<sup>0</sup>C the CPU dies (let's say we heavily
overclocked it) and there is no going back. This type of
discontinuities is called an <span style="font-weight: bold;">irreversible
discontinuity</span> and can be described <span
 style="font-weight: bold;"></span> by the <span
 style="font-weight: bold;">STN </span><span style="font-weight: bold;">state
transient
network
</span><span style="font-weight: bold;">construct</span>. In <span
 style="font-weight: bold;">pyDAE</span>&nbsp;<span
 style="font-weight: bold;"></span>it is given by the following
statement:
</p>
<pre>STN("CPU")<br><br>STATE("Normal")<br> ... (equations go here)<br>SWITCH_TO("PowerSaving", CPULoad() &lt; 0.05) <br>SWITCH_TO("Fried", T() &gt; 110)<br><br><br>STATE("PowerSaving") <br> ... (equations go here)<br>SWITCH_TO("Normal", CPULoad() &gt;= 0.05)<br>SWITCH_TO("Fried", T() &gt; 110)<br><br>STATE("Normal")<br> ... (equations go here)<br><br>END_STN()</pre>
<p>while in <span style="font-weight: bold;">cDAE</span> by:<br>
</p>
<pre>STN("CPU");<br><br>STATE("Normal");<br> ... (equations go here)<br>SWITCH_TO("PowerSaving", CPULoad() &lt; 0.05); <br>SWITCH_TO("Fried", T() &gt; 110);<br><br><br>STATE("PowerSaving");<br> ... (equations go here)<br>SWITCH_TO("Normal", CPULoad() &gt;= 0.05);<br>SWITCH_TO("Fried", T() &gt; 110);<br><br>STATE("Normal");<br> ... (equations go here)<br><br>END_STN();</pre>
<p>More information about state transition networks can be found in <a
 href="pydae_user_guide.html">pyDAE User Guide</a> and <a
 href="api_ref/core.html#daeSTN">pyDAE API Reference</a>. Also, do not
forget to have a look on <a href="tutorials.html">tutorials</a>.<br>
</p>
<h3><a name="Ports"></a>Ports</h3>
<p>Ports are used to connect two models. Like models, they may contain
domains, parameters and variables. For instance, in <span
 style="font-weight: bold;">pyDAE</span> ports can be defined by the
following
statements:<br>
</p>
<pre>class myPort(daePort):<br>    def __init__(self, Name, Type, Parent = None, Description = ""):<br>        daePort.__init__(self, Name, Type, Parent, Description)<br>        ... (here go declarations of domains, parameters and variables)<br></pre>
<p>while in <span style="font-weight: bold;">cDAE</span>
by:</p>
<pre>class myPort : public daePort<br>{<br>public:<br> &nbsp;&nbsp; myPort(string strName, daeePortType eType, daeModel* pParent, string strDescription = "") <br>         : daePort(strName, eType, pParent, strDescription)<br>   &nbsp;{<br>        ... (here go additional properties of domains, parameters and variables)<br>    }<br><br>public:<br>    ... (here go declarations of domains, parameters and variables)<br>};</pre>
<p>
</p>
<p>
</p>
<p>More information about ports can be found in <a
 href="pydae_user_guide.html">pyDAE User Guide</a> and <a
 href="api_ref/core.html#daePort">pyDAE API Reference</a>. Also, do not
forget to have a look on <a href="tutorials.html">tutorials</a>.<br>
</p>
<p>
</p>
<h2><a name="2._Definition_of_a_simulation"></a>Simulation</h2>
<p>As it was mentione above, simulation of a process can be considered
as the model run for
certain
input conditions. To define a simulation in <span
 style="font-weight: bold;">DAE Tools</span>
the following tasks have
to be done:<br>
</p>
<p>1. Derive a new simulation class<br>
</p>
<ul>
  <li>Specify a model to simulate</li>
  <li>Specify its domains and parameters information</li>
  <li>Fix the degrees of freedom by assigning the values to certain
variables</li>
  <li>Set the initial conditions for differential variables</li>
  <li>Set the other variables' information: initial guesses, absolute
tolerances, etc</li>
  <li>Specify the operating procedure. It can be either a simple run
for a specified period of time (default)&nbsp; or a complex one where
various actions
can be taken during the simulation</li>
</ul>
<p>2. Specify DAE and LA solvers<br>
3. Specify a data reporter and a data receiver, and connect them<br>
4. Set a time horizon, reporting interval, etc<br>
5. Do the initialization of the DAE system<br>
6. Save model report and/or runtime model report (to inspect expanded
equations etc)<br>
7. Run the simulation </p>
<p>Simulations in <span style="font-weight: bold;">pyDAE</span>
can be defined
by the following
construct:<br>
</p>
<pre>class mySimulation(daeDynamicSimulation):<br>    def __init__(self):<br>        daeDynamicSimulation.__init__(self)<br>        self.m = myModel("myModel", "Description") <br>          <br>    def SetUpParametersAndDomains(self):<br>        ... (here we set up domains and parameters)<br>    <br>    def SetUpVariables(self):<br>        ... (here we set up degrees of freedom, initial conditions, initial guesses, etc)<br><br>    def Run(self):<br>        ... (here goes a custom operating procedure, if needed)<br></pre>
<p>while in <span style="font-weight: bold;">cDAE</span>
by:</p>
<pre>class mySimulation : public daeDynamicSimulation<br>{<br>public:<br>    mySimulation(void) : m("myModel", "Description")<br>    {<br>        SetModel(&amp;m);<br>    }<br><br>public:<br>    void SetUpParametersAndDomains(void)<br>    {<br>        ... (here we set up domains and parameters)<br>    }<br><br>    void SetUpVariables(void)<br>    {<br>        ... (here we set up degrees of freedom, initial conditions, initial guesses, etc)<br>    }<br>    <br>    void Run(void)<br>    {<br>        ... (here goes a custom operating procedure, if needed)<br>    }<br>    <br>public:<br>    myModel m;<br>};</pre>
<h3>Running a simulation</h3>
<p>Simulations in <span style="font-weight: bold;">pyDAE</span> can be
run
by in two modes:<br>
</p>
<ol>
  <li>By using PyQt4 graphical user interface (GUI)</li>
  <li>From the shell</li>
</ol>
<p><br>
</p>
<p>1) Running a simulation from the GUI (<span
 style="font-weight: bold;">pyDAE</span> only):<br>
</p>
<pre># Import modules<br>import sys<br>from time import localtime, strftime<br>from PyQt4 import QtCore, QtGui<br><br># Create QtApplication object<br>app = QtGui.QApplication(sys.argv)<br><br># Create simulation object<br>simulation = simTutorial()<br><br># Report ALL variables in the model<br>simulation.m.SetReportingOn(True)<br><br># Show the daeSimulator window<br>simulator  = daeSimulator(app, simulation)<br>simulator.show()<br><br># Execute applications main loop<br>app.exec_()</pre>
<p>Here the default log, and data reporter objects will be used, while
the user can choose DAE and LA solvers and specify time horizon and
reporting interval.<br>
</p>
<p><br>
</p>
<p>2) Running a simulation from the shell:<br>
</p>
<p>In <span style="font-weight: bold;">pyDAE</span>:<br>
</p>
<p></p>
<pre># Import modules<br>import sys<br>from time import localtime, strftime<br><br># Create Log, Solver, DataReporter and Simulation object<br>log          = daeStdOutLog()<br>solver       = daeIDASolver()<br>datareporter = daeTCPIPDataReporter()<br>simulation   = simTutorial()<br><br># Set the linear solver (optional)<br>lasolver     = pyTrilinosAmesos.CreateTrilinosAmesosSolver("Amesos_Superlu")<br>solver.SetLASolver(eThirdParty, lasolver)<br><br># Report ALL variables in the model<br>simulation.m.SetReportingOn(True)<br><br># Set the time horizon (1000 seconds) and the reporting interval (10 seconds)<br>simulation.SetReportingInterval(10)<br>simulation.SetTimeHorizon(1000)<br><br># Connect data reporter (use the default TCP/IP connection string)<br>simName = simulation.m.Name + strftime(" [%d.%m.%Y %H:%M:%S]", localtime())<br>if(datareporter.Connect("", simName) == False):<br>    sys.exit()<br><br># Initialize the simulation<br>simulation.Initialize(solver, datareporter, log)<br><br># Solve at time = 0 (initialization)<br>simulation.SolveInitial()<br><br># Run<br>simulation.Run()<br></pre>
<p>while in <span style="font-weight: bold;">cDAE</span>
by:</p>
<pre>// Create Log, Solver, DataReporter and Simulation object<br>boost::scoped_ptr&lt;daeDynamicSimulation_t&gt; pSimulation(new simTutorial);  <br>boost::scoped_ptr&lt;daeDataReporter_t&gt;      pDataReporter(daeCreateTCPIPDataReporter());<br>boost::scoped_ptr&lt;daeIDASolver&gt;	          pDAESolver(daeCreateIDASolver());<br>boost::scoped_ptr&lt;daeLog_t&gt;               pLog(daeCreateStdOutLog());<br><br>// Report ALL variables in the model<br>pSimulation-&gt;GetModel()-&gt;SetReportingOn(true);<br><br>// Set the time horizon and the reporting interval<br>pSimulation-&gt;SetReportingInterval(10);<br>pSimulation-&gt;SetTimeHorizon(100);<br> <br>// Connect data reporter<br>string strName = pSimulation-&gt;GetModel()-&gt;GetName();<br>if(!pDataReporter-&gt;Connect(strName, string("Tutorial1")))<br>    return;<br><br>// Initialize the simulation<br>pSimulation-&gt;Initialize(pDAESolver.get(), pDataReporter.get(), pLog.get());<br><br>// Solve at time = 0 (initialization)<br>pSimulation-&gt;SolveInitial();<br><br>// Run<br>pSimulation-&gt;Run();<br></pre>
<p><br>
More information about simulation can be found in <a
 href="pydae_user_guide.html">pyDAE User Guide</a> and <a
 href="api_ref/activity.html#daeDynamicSimulation">pyDAE API Reference</a>.
Also,
do
not
forget
to
have
a
look
on
<a href="tutorials.html">tutorials</a>.<br>
</p>
<h2><a name="3._Processing_of_the_results"></a>Processing the
results</h2>
<p>The simulation results can be easily plotted by using <span
 style="font-weight: bold;">DAE Plotter</span> application. It is
possible to choose between 2D and 3D plots. After choosing a desired
type, a <span style="font-weight: bold;">Choose variable</span> (given
in <span style="font-weight: bold;">Figure 5.</span>) dialog appears
where a user has to select a variable to
plot and specify information about domains - fix some of them while
leaving another free by selecting <span style="font-weight: bold;">*</span>
from the list (to create a 2D plot you need one domain free, while for
a 3D plot you need two free domains).&nbsp; A typical 2D plot is
presented in <span style="font-weight: bold;">Figure 6</span>.<br>
</p>
<br>
<p><br>
</p>
<p style="text-align: center;"><img style="width: 663px; height: 534px;"
 alt="" src="images/Screenshot-ChooseVariable.png"><br>
</p>
<div style="text-align: center;"><span style="font-weight: bold;">Figure
5.
Choose
variable
dialog for a 2D plot<br>
</span></div>
<p><br>
</p>
<p><br>
</p>
<p style="text-align: center;"><img style="width: 606px; height: 484px;"
 alt="" src="images/Screenshot-Results.png"><br>
</p>
<div style="text-align: center;"><span style="font-weight: bold;">Figure
6.
Example
2D
plot<br>
</span></div>
<p><br>
</p>
<p><br>
</p>
<p><br>
</p>
<p><br>
</p>
<p><br>
<br>
</p>
</div>
<br>
</div>
<!-- content-wrap ends here --> </div>
</div>
<!-- footer starts here -->
<div id="footer">
<div id="footer-content">
<div class="col float-left">
<p> &copy; Copyright: Dragan Nikolic 2010<br>
</p>
</div>
<div class="col float-left">
<p> <a href="http://www.daetools.com"><strong>DAE Tools Project</strong></a>
</p>
</div>
<div class="col2 float-right">
<p> Design by: <a href="http://www.styleshout.com/"><strong>Styleshout</strong></a>
&nbsp; &nbsp; Valid <a
 href="http://jigsaw.w3.org/css-validator/check/referer"><strong>CSS</strong></a>
| <a href="http://validator.w3.org/check/referer"><strong>XHTML</strong></a>
</p>
</div>
</div>
</div>
<!-- footer ends here --><!-- wrap ends here --> </div>
</body>
</html>
